Ribbon¶
Overview¶
- You can extend the UI configuration of the ribbon with a manifest.
- You can freely configure tabs and groups on the ribbon, and place buttons to call commands and check boxes to display/change the ON/OFF status on the ribbon.
Ribbon element¶
Ribbon elements that can be expanded with extensions are as follows.
- Tab
- Group
- Single control
- Button
- Checkbox
- Separator
- Composite control
- Button group
- Stack panel
- Menu
- Split button
Details for each element¶
tab (tabs element)
-
Tabs that make up the ribbon
-
Property
Key Description Range Requiredid An ID that uniquely identifies the tab. A unique string for all components of the ribbon. 1 Character string that represents the ID Required label Tab label Arbitrary string Required orderBefore/orderAfter The ID of the ribbon element that indicates the relative position to add the tab. 2
If not specified, it will be added before the [Help] tab. If a tab with the same ID already exists, no new tab will be added and the existing tab position will remain.
Please refer to Predefined ID for system standard built-in ribbon element ID.A string that represents an ID - visible Display state of the target element. Displayed when omitted or specified as true. Hide when false is specified. "true", "false" - groups Array of groups that make up a tab Object array - -
Child element type
- Group
Group (groups element)
-
Group that divides the ribbon tab
-
Properties
Key Description Range Requiredid An ID that uniquely identifies the target element. A unique string for all components of the ribbon. 1 Character string that represents the ID Required label Group label Any string Required orderBefore/orderAfter ID of the ribbon element that indicates the relative position to add the target element. 2
For the ID of the system standard built-in ribbon element, refer to Defined ID.A string that represents an ID - visible Display state of the target element. Displayed if omitted or specified as true. Hide when false is specified. "true", "false" - controls Array of controls to place in the group Object array - -
Types of controls that can be placed as child elements
- Button
- CheckBox
- Separator
- ButtonGroup
- StackPanel
- Menu
- SplitButton
Button (type: Button)
-
Command execution button on the ribbon
- You can assign a command to execute when the button is pressed.
- The enable/disable status and toggle status of the button are linked with the assigned command.
-
Properties
Key Description Range Requiredtype Element type. "Button" Required id ID that uniquely identifies the target element. A unique string for all components of the ribbon. 1 Character string that represents the ID Required label Button label Arbitrary string Required description The description displayed in the tooltip Any string - orderBefore/orderAfter ID of the ribbon element that indicates the relative position to add the target element. 2 Character string representing ID - visible Display state of the target element. Displayed when omitted or specified as true. Hide when false is specified. "true", "false" - isEnabled Property name that holds the enabled/disabled state of the button. If omitted, it is linked to the status of the assigned command. Character string representing the property name - isChecked The property name that holds the toggle state of the button. If omitted, it is linked to the status of the assigned command. Character string that represents the property name - imageSmall PNG file path for the small icon that appears on the button. 3 Character string representing relative path - imageLarge Large icon PNG file path to display on the button. 3 Character string that represents relative path - command The ID of the command assigned to the button. ID string Required
Check box (type: CheckBox)
-
Checkbox
- The display of the check box changes according to the value of the property associated with the isChecked property.
- Manipulating the checkbox updates the associated property value.
-
Property
Key Description Range Requiredtype Element type. "CheckBox" Required id ID that uniquely identifies the target element. A unique string for all components of the ribbon. 1 Character string that represents the ID Required label Checkbox label Arbitrary string Required orderBefore/orderAfter ID of the ribbon element that indicates the relative position to add the target element. 2 Character string representing ID - visible Display state of the target element. Displayed when omitted or specified as true. Specify false to hide. "true", "false" - isChecked Property name that holds the checked status Character string that represents the property name Required
Separator (type: Separator)
-
Separator.
-
Property
Key Description Range Requiredtype The type of element. "Separator" Required id ID that uniquely identifies the tab. A unique string for all components of the ribbon. 1 Character string that represents the ID Required
ButtonGroup (type: ButtonGroup)
-
A container that displays multiple buttons side by side like a toolbar
-
Property
Key Description Range Requiredtype Element type. "ButtonGroup" Required id An ID that uniquely identifies the target element. A unique string for all components of the ribbon. 1 Character string that represents the ID Required orderBefore/orderAfter ID of the ribbon element that indicates the relative position to add the target element. 2 Character string representing ID - visible The display status of the target element. Displayed when omitted or specified as true. Specify false to hide. "true", "false" - controls array of controls placed side by side object array - -
Types of controls that can be placed as child elements
- Button (small)
- Separator
Stack Panel (type: StackPanel)
-
A container that displays multiple buttons vertically
- Use this when you want to display small image buttons vertically.
-
Property
Key Description Range Requiredtype Element type. "StackPanel" Required id An ID that uniquely identifies the target element. A unique string for all components of the ribbon. 1 Character string that represents the ID Required orderBefore/orderAfter ID of the ribbon element that indicates the relative position to add the target element. 2 Character string representing ID - visible Display state of the target element. Displayed if omitted or specified as true. Specify false to hide. "true", "false" - controls An array of controls arranged side by side. Up to 3 controls can be placed. Object array - -
Types of controls that can be placed as child elements
- Button (small)
- SplitButton (small)
- ButtonGroup
- CheckBox
- Menu
Menu (type: Menu)
-
A container that displays multiple buttons in a pull-down menu format
-
Property
Key Description Range Requiredtype The type of element. "Menu" Required id An ID that uniquely identifies the target element. A unique string for all components of the ribbon. 1 Character string representing ID Required orderBefore/orderAfter ID of the ribbon element that indicates the relative position to add the target element. 2 Character string representing ID - visible Display state of the target element. Displayed if omitted or specified as true. Hide when false is specified. "true", "false" - imageLarge PNG file path of the icon to display on the button. A string that represents a relative path - controls array of controls placed side by side object array - -
Types of controls that can be placed as child elements
- Button (small)
- Separator
Split button (type: SplitButton)
-
A container that has the function of a button that can press itself to execute a command, and also displays another button in a pull-down menu format.
-
Properties
Key Description Range Requiredtype The type of element. "SplitButton" Required id ID that uniquely identifies the target element. A unique string for all components of the ribbon. 1 Character string representing ID Required label Button label Arbitrary string Required description Description displayed in the tooltip Arbitrary string - orderBefore/orderAfter ID of the ribbon element that indicates the relative position to add the target element. 2 Character string that represents the ID - visible Display state of the target element. Displayed when omitted or specified as true. Hide when false is specified. "true", "false" - isEnabled Property name that holds the enabled/disabled state of the button. If omitted, it is linked to the status of the assigned command. Character string that represents the property name - isChecked Property name that holds the toggle state of the button. If omitted, it is linked to the status of the assigned command. Character string that represents the property name - imageSmall PNG file path for the small icon that appears on the button. 3 Character string representing relative path - imageLarge PNG file path of the large icon to display on the button. 3 Character string that represents relative path - command Command ID assigned to the button Character string that represents the ID Required controls Array of controls that are arranged side by side Object array - -
Types of controls that can be placed as child elements
- Menu
Multilingual¶
- The values of the
Label
andDescription
properties can be localized (localized). - Instead of specifying the display string as the property value, specify it as "% resource string name %" and it will be replaced with the resource string in the localized locale file.
Detail
- For details on multilingual support, refer to Development Guide> Common> Multilingual Support.
Ribbon definition example¶
{
"name": "My Extensition",
"main": "main.cs",
"lifecycle": "project",
"baseprofile": "MBD",
"extensionPoints": {
"ribbon": {
"tabs": [
{
"id": "MBD",
"label": "MBD",
"orderAfter": "System.View",
"groups": [
{
"id": "MbdSync",
"label": "block",
"controls": [
{
"id": "MbdSync.CreateBlock",
"type": "Button",
"imageLarge": "resources/createBlock.png",
"command": "myExtension.createBlock"
},
{
"type": "Menu",
"label": "Check block",
"isEnabled": "MyProperty1",
"imageLarge": "resources/blocks.png",
"controls": [
{
"id": "MbdSync.UpdateBlock",
"type": "Button",
"imageSmall": "resources/updateBlock.png",
"label": "Update block",
"description": "Update the block",
"command": "myExtension.updateBlock"
}
]
},
{
"type": "StackPanel",
"controls": [
{
"id": "MbdSync.UpdateBlock",
"type": "Button",
"isChecked": "myProperty2",
"imageSmall": "resources/updateBlock.png",
"label": "Update block",
"description": "Update the block",
"command": "myExtension.updateBlock"
},
{
"type": "Separator"
},
{
"id": "MbdSync.UpdateBlock",
"type": "Button",
"imageSmall": "resources/updateBlock.png",
"label": "Update block",
"description": "Update the block",
"command": "myExtension.updateBlock"
}
]
}
]
},
{
"id": "CodeGen",
"label": "Generate Source Code",
"controls": [
{
"id": "CodeGen.GenerateCode",
"type": "Button",
"imageLarge": "resources/generate.png",
"command": "myExtension.generateCode"
}
]
}
]
}
]
},
"commands": [
{
"id": "myExtension.createBlock",
"execFunc": "createBlock"
},
{
"id": "myExtension.updateBlock",
"execFunc": "updateBlock"
},
{
"id": "myExtension.generateCode",
"execFunc": "generateCode"
}
]
}
}
-
-If you specify the same ID as an existing component, it will be merged into the same component. Otherwise, a new component will be created. ↩↩↩↩↩↩↩↩↩
-
-You can specify the ID of the sibling element that indicates the relative position. You can specify either before (orderBefore) or after (orderAfter) the specified element. If not specified for elements other than tabs, they are added to the end of sibling elements. ↩↩↩↩↩↩↩↩
-
-Set either imageSmall or imageLarge. The size of the displayed icon is adjusted according to the layout in the ribbon. Set imageSmall to the elements of StackPanel. ↩↩↩↩